<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Resources</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">

</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>


        <h1 class="title">Native Windows GUI: Resources</h1>

        Resources are non-ui components that are usually used by GUI controls. This includes images, fonts, cursors, and dialogs.<br><br>

        Most resource can be loaded from file, memory, or from embed resources.<br><br>

        This section will go over images, fonts, and cursors. The next section covers the dialog.

        <br/><br/>

        <h3>Images & Icons</h3>

        Out of the box, winapi only supports bitmap (.bmp) and icons (.ico). Bitmap and icons are used by many controls, and some
        meta resouces like <code>ImageList</code>. Use a <code>ImageFrame</code> control to display icons and bitmap in a Window.
        <br/><br/>

        By setting the <code>strict</code> builder parameter to <code>false</code>, NWG will load a default windows resource if the source file cannot be found
        (instead of returning an error).

<div class="highlight"><pre style="width: auto"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">load_bitmap</span><span class="p">()</span><span class="w"> </span>-&gt; <span class="nc">nwg</span>::<span class="n">Bitmap</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="k">mut</span><span class="w"> </span><span class="n">bitmap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">default</span><span class="p">();</span><span class="w"></span>

<span class="w">    </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">source_file</span><span class="p">(</span><span class="nb">Some</span><span class="p">(</span><span class="s">&quot;Hello.bmp&quot;</span><span class="p">))</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">strict</span><span class="p">(</span><span class="kc">true</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">bitmap</span><span class="p">);</span><span class="w"></span>

<span class="w">    </span><span class="n">bitmap</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>


        <br/><br/>

        <h3>Windows Imaging Component (WIC)</h3>

        Now, because we're no longer in 3000 BC, you probably want to support more image types. Png and jpeg specifically. Thanksfully, NWG seamlessly wraps the 
        windows imaging component. This adds the following formats: .bmp(v5, with transparency), gif, ico, jpeg, png, tiff, vnd, and dds.<br/><br/>

        To enable the WIC, just use the <code>image-decoder</code> feature. When this is enabled, all the above formats will be supported by <code>Bitmap</code>.
        <br/><br/>

        The image decoder feature also enables the <code>ImageDecoder</code> resource. Which allows you load image files manually and read the pixel data.
        Ability to load images from streams (ex the internet) will probably be added in the future (after the 1.0 release).
        <br/><br/>

        See the <a href="https://github.com/gabdube/native-windows-gui/blob/master/native-windows-gui/examples/image_decoder_d.rs">image decoder</a> example
        <br/><br/>


        <h3>Helper functions</h3>

        The builder api can be cumbersome, that's why Native Windows GUI also includes helper functions to load resources in a single line.
        <br/><br/>

        The helper functions all have a similar signature: <code>Bitmap::from_*</code>, <code>Icon::from_*</code>. 
        <br/><br/>

        You can also check out the <a href="https://docs.rs/native-windows-gui/1.0.12/native_windows_gui/struct.Bitmap.html">docs.rs documentation</a>.
        <br/><br/>

<div class="highlight"><pre style="width: auto"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>

<span class="k">static</span><span class="w"> </span><span class="n">EMBEDDED_BITMAP</span>: <span class="kp">&amp;</span><span class="p">[</span><span class="kt">u8</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="fm">include_bytes!</span><span class="p">(</span><span class="s">&quot;cat.jpg&quot;</span><span class="p">);</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">load_resources</span><span class="p">()</span><span class="w"> </span>-&gt; <span class="nb">Result</span><span class="o">&lt;</span><span class="p">(),</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NwgError</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">bitmap1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">from_file</span><span class="p">(</span><span class="s">&quot;hello.png&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">bitmap2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">from_bin</span><span class="p">(</span><span class="n">EMBEDDED_BITMAP</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>

<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">icon1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Icon</span>::<span class="n">from_file</span><span class="p">(</span><span class="s">&quot;hey.ico&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">load_image_from_embedded</span><span class="p">()</span><span class="w"> </span>-&gt; <span class="p">[</span><span class="n">Bitmap</span><span class="p">;</span><span class="w"> </span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">embed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">EmbedResource</span>::<span class="n">load</span><span class="p">(</span><span class="nb">None</span><span class="p">).</span><span class="n">unwrap</span><span class="p">();</span><span class="w"></span>

<span class="w">    </span><span class="cm">/*</span>
<span class="cm">        // myapp.rc</span>

<span class="cm">        BALL BITMAP &quot;ball.bmp&quot;</span>
<span class="cm">        HELLO IMAGE &quot;test.png&quot;</span>
<span class="cm">        NICE IMAGE &quot;test.jpg&quot;</span>
<span class="cm">    */</span><span class="w"></span>

<span class="w">    </span><span class="p">[</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">from_embed</span><span class="p">(</span><span class="o">&amp;</span><span class="n">embed</span><span class="p">,</span><span class="w"> </span><span class="nb">None</span><span class="p">,</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="s">&quot;BALL&quot;</span><span class="p">)),</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">from_embed</span><span class="p">(</span><span class="o">&amp;</span><span class="n">embed</span><span class="p">,</span><span class="w"> </span><span class="nb">None</span><span class="p">,</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="s">&quot;HELLO&quot;</span><span class="p">)),</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">Bitmap</span>::<span class="n">from_embed</span><span class="p">(</span><span class="o">&amp;</span><span class="n">embed</span><span class="p">,</span><span class="w"> </span><span class="nb">None</span><span class="p">,</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="s">&quot;NICE&quot;</span><span class="p">)),</span><span class="w"></span>
<span class="w">    </span><span class="p">]</span><span class="w"></span>
<span class="p">}</span><span class="w"> </span>
</pre></div>
            

        <h3>Fonts</h3>

        Native-windows-gui supports <code>.ttf</code> and <code>.otf</code> font files. All controls that display text have a 
        <code>set_font</code> and <code>get_font</code> method to set their font.
        <br><br>

        NWG has access to all the fonts families installed on the system. It's also possible to add new fonts temporarily using the <code>Font::add_font / Font::remove_font</code> 
        or <code>Font::add_memory_font / Font::remove_memory_font</code>.<b>Those methods works globally.</b> 
        <br>

<div class="highlight"><pre style="width: auto"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">Font</span>::<span class="n">add_font</span><span class="p">(</span><span class="s">&quot;./MyFont.ttf&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="c1">// Application runtime</span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">Font</span>::<span class="n">remove_font</span><span class="p">(</span><span class="s">&quot;./MyFont.ttf&quot;</span><span class="p">);</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
<br><br>
            

        Once the font families are loaded, a `Font` resource must be created. Just like the other resources, this is done using the Font builder.

<div class="highlight"><pre style="width: auto"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">build_font</span><span class="p">()</span><span class="w"> </span>-&gt; <span class="nc">nwg</span>::<span class="n">Font</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="k">mut</span><span class="w"> </span><span class="n">font</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Font</span>::<span class="n">default</span><span class="p">();</span><span class="w"></span>

<span class="w">    </span><span class="n">nwg</span>::<span class="n">Font</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">size</span><span class="p">(</span><span class="mi">16</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">family</span><span class="p">(</span><span class="s">&quot;Arial&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">weight</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">font</span><span class="p">);</span><span class="w"></span>

<span class="w">    </span><span class="n">font</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">set_font</span><span class="p">(</span><span class="n">button</span>: <span class="kp">&amp;</span><span class="nc">nwg</span>::<span class="n">Button</span><span class="p">,</span><span class="w"> </span><span class="n">font</span>: <span class="kp">&amp;</span><span class="nc">nwg</span>::<span class="n">Font</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">button</span><span class="p">.</span><span class="n">set_font</span><span class="p">(</span><span class="nb">Some</span><span class="p">(</span><span class="n">font</span><span class="p">));</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
        
        <br/><br/>

        <h3>Cursors</h3>

        Cursors are icons that can be used in place of the default Windows mouse cursor. Cursors can be custom, loaded from <code>.cur</code> files, or they can be loaded
        from the system default cursors (using <code>OemCursor</code>). 
        <br/><br/>

        Currently cursors can only be set globally using <code>GlobalCursor::set</code> (behind the <code>cursor</code> feature). Furthermore, this method must be called everytime the cursor moves in a control
        because the default cursor is replaced automatically by Windows on mouse events. This behavior will probably change in the future.


<div class="highlight"><pre style="width: auto"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">set_cursor</span><span class="p">(</span><span class="n">window</span>: <span class="kp">&amp;</span><span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"> </span><span class="n">cursor</span>: <span class="nc">nwg</span>::<span class="n">Cursor</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">full_bind_event_handler</span><span class="p">(</span><span class="o">&amp;</span><span class="n">window</span><span class="p">.</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="k">move</span><span class="w"> </span><span class="o">|</span><span class="n">event</span><span class="p">,</span><span class="w"> </span><span class="n">event_data</span><span class="p">,</span><span class="w"> </span><span class="n">handle</span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="k">match</span><span class="w"> </span><span class="n">event</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="n">nwg</span>::<span class="n">Event</span>::<span class="n">OnMousePress</span><span class="p">(</span><span class="n">_</span><span class="p">)</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Event</span>::<span class="n">OnMouseMove</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                </span><span class="n">nwg</span>::<span class="n">GlobalCursor</span>::<span class="n">set</span><span class="p">(</span><span class="o">&amp;</span><span class="n">cursor</span><span class="p">)</span><span class="w"></span>
<span class="w">            </span><span class="p">},</span><span class="w"></span>
<span class="w">            </span><span class="n">_</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">});</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>

        <br/><br/>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
